I generally agree with this approach!

Currently, I can only see those roles being passed currently directly in the JWT payload: https://github.com/openedx/edx-platform/blob/acbf50a7dd8492a9fb80f35ffbc561b668fe619d/openedx/core/djangoapps/oauth_dispatch/jwt.py#L275-L276 for administrator and superuser roles. We haven't decided whether to use those django-native definitions still or move them into the authZ. What makes more sense to me, simplicity-wise, is to keep using those and implement other feature-specifics into the authz system but we'd need a way of integrating them seamlessly. In any case, that would mean continuing to send the same roles in the same format. What do you think?

Yes, the existing roles will continue being passed to the JWT as-is, and for now will still be picked by the current auth code.

The new AuthZ implementation won't directly care about these, unless we find any special case that would need it, in that case we would do an "OR" on the specific action, for example:

Let's say that we identify that superuser should always have access to "read" any Library, on the GET library endpoint handler, we would validate like (pseudo code):

has_access = is_superuser() or new_authz_has_permission("library-read", user, library)

where is_superuser() is the existing code that validates this, and new_authz_has_permission is our new implementation.

Would this make sense?

Yes, that makes total sense. I think this is the simplest approach given the current state.

Another case came to my attention last week while I was discussing with my team about how the new authz framework should interact with other systems: Aspects. Currently, this is how the system manages access to its resources:
https://github.com/openedx/tutor-contrib-aspects/blob/e0db9f51250fd842dcdcce8abb57befc17cff0ae/tutoraspects/templates/aspects/apps/superset/pythonpath/openedx_sso_security_manager.py#L179-L208 - roles are sent in the JWT. It looks like we only use admin and superuser -I think- so it should work the same.

If this is not the case, then we'll need to decide on our next steps for handling this specific case of authorization management, but it's not an immediate blocker. Should we document this somewhere?

FYI @bmtcril

I think if the existing JWT implementation doesn't change that is fine for Aspects' use of the superuser role to grant access to all reports.

However in the long term, the way Aspects uses the courses endpoint to find which roles the user has on individual courses will have to change. Ideally we would have an endpoint that would allow us to get all courses that a specific user has a specific permission on instead of having to query all courses that the user is associated with, then do further API calls to determine if they have the necessary permission to view reports for each course.

I'm not sure those details are relevant to this ADR, but we may want to capture the generic use case for "external service needs to check LMS/Studio permissions over API" somewhere.

This is not actually important but the bullets in this section are nested too far and in the rendered view they view as quotes (https://openedx-authz--34.org.readthedocs.build/en/34/decisions/0003-jwt-usage.html#possible-methods). Probably not actually worth fixing, but worth paying attention to for more user-facing documentation.